home *** CD-ROM | disk | FTP | other *** search
/ Amiga Magazin: Amiga-CD 1996 March / Amiga-CD 1996 #3.iso / pd-software / mui_3.1 / developer / autodocs / mui_application.doc < prev    next >
Text File  |  1996-01-19  |  45KB  |  1,471 lines
  1. TABLE OF CONTENTS
  2.  
  3. Application.mui/Application.mui
  4. Application.mui/MUIA_Application_Active
  5. Application.mui/MUIA_Application_Author
  6. Application.mui/MUIA_Application_Base
  7. Application.mui/MUIA_Application_Broker
  8. Application.mui/MUIA_Application_BrokerHook
  9. Application.mui/MUIA_Application_BrokerPort
  10. Application.mui/MUIA_Application_BrokerPri
  11. Application.mui/MUIA_Application_Commands
  12. Application.mui/MUIA_Application_Copyright
  13. Application.mui/MUIA_Application_Description
  14. Application.mui/MUIA_Application_DiskObject
  15. Application.mui/MUIA_Application_DoubleStart
  16. Application.mui/MUIA_Application_DropObject
  17. Application.mui/MUIA_Application_ForceQuit
  18. Application.mui/MUIA_Application_HelpFile
  19. Application.mui/MUIA_Application_Iconified
  20. Application.mui/MUIA_Application_Menu
  21. Application.mui/MUIA_Application_MenuAction
  22. Application.mui/MUIA_Application_MenuHelp
  23. Application.mui/MUIA_Application_Menustrip
  24. Application.mui/MUIA_Application_RexxHook
  25. Application.mui/MUIA_Application_RexxMsg
  26. Application.mui/MUIA_Application_RexxString
  27. Application.mui/MUIA_Application_SingleTask
  28. Application.mui/MUIA_Application_Sleep
  29. Application.mui/MUIA_Application_Title
  30. Application.mui/MUIA_Application_UseCommodities
  31. Application.mui/MUIA_Application_UseRexx
  32. Application.mui/MUIA_Application_Version
  33. Application.mui/MUIA_Application_Window
  34. Application.mui/MUIM_Application_AddInputHandler
  35. Application.mui/MUIM_Application_CheckRefresh
  36. Application.mui/MUIM_Application_GetMenuCheck
  37. Application.mui/MUIM_Application_GetMenuState
  38. Application.mui/MUIM_Application_Input
  39. Application.mui/MUIM_Application_InputBuffered
  40. Application.mui/MUIM_Application_Load
  41. Application.mui/MUIM_Application_NewInput
  42. Application.mui/MUIM_Application_OpenConfigWindow
  43. Application.mui/MUIM_Application_PushMethod
  44. Application.mui/MUIM_Application_RemInputHandler
  45. Application.mui/MUIM_Application_ReturnID
  46. Application.mui/MUIM_Application_Save
  47. Application.mui/MUIM_Application_SetConfigItem
  48. Application.mui/MUIM_Application_SetMenuCheck
  49. Application.mui/MUIM_Application_SetMenuState
  50. Application.mui/MUIM_Application_ShowHelp
  51. Application.mui/Application.mui
  52.  
  53.     Application class is the master class for all
  54.     MUI applications. It serves as a kind of anchor
  55.     for all input, either coming from the user or
  56.     somewhere from the system, e.g. commodities
  57.     or ARexx messages.
  58.  
  59.     An application can have any number of sub windows,
  60.     these windows are the children of the application.
  61. Application.mui/MUIA_Application_Active
  62.  
  63.     NAME
  64.     MUIA_Application_Active -- (V4 ) [ISG], BOOL
  65.  
  66.     FUNCTION
  67.     This attribute reflects the state that the user adjusted
  68.     with commodities Exchange. MUI itself doesn't pay any
  69.     attention to it, this is up to you.
  70.  
  71.     SEE ALSO
  72.     MUIA_Application_Broker
  73. Application.mui/MUIA_Application_Author
  74.  
  75.     NAME
  76.     MUIA_Application_Author -- (V4 ) [I.G], STRPTR
  77.  
  78.     FUNCTION
  79.     Name of the applications author.
  80.  
  81.     EXAMPLE
  82.     see MUIA_Application_Title
  83.  
  84.     SEE ALSO
  85.     MUIA_Application_Title, MUIA_Application_Copyright,
  86.     MUIA_Application_Version, MUIA_Application_Description,
  87.     MUIA_Application_Base
  88. Application.mui/MUIA_Application_Base
  89.  
  90.     NAME
  91.     MUIA_Application_Base -- (V4 ) [I.G], STRPTR
  92.  
  93.     FUNCTION
  94.     The basename for an application. This name is used
  95.     for the builtin ARexx port and for some internal
  96.     file management.
  97.  
  98.     A basename must neither contain spaces nor any
  99.     special characters such as ":/()#?*...".
  100.  
  101.     When your program is a single task application
  102.     (i.e. MUIA_Application_SingleTask is TRUE), the
  103.     base name will be used without further modification.
  104.  
  105.     Otherwise, it gets a ".1", ".2", etc. appended,
  106.     depending on how many applications are already
  107.     running. If you need to know the name of your
  108.     ARexx port, you can query the base name attribute
  109.     after the application is created.
  110.  
  111.     EXAMPLE
  112.     see MUIA_Application_Title
  113.  
  114.     SEE ALSO
  115.     MUIA_Application_Title, MUIA_Application_Version,
  116.     MUIA_Application_Author, MUIA_Application_Copyright,
  117.     MUIA_Application_Description
  118. Application.mui/MUIA_Application_Broker
  119.  
  120.     NAME
  121.     MUIA_Application_Broker -- (V4 ) [..G], Broker *
  122.  
  123.     FUNCTION
  124.     If you need to attach some additional commodities objects
  125.     to your application (e.g. because you need lots of hotkeys),
  126.     you can obtain a pointer to the applications Broker structure
  127.     and add some commodities objects.
  128.  
  129.     MUI will free the complete broker when the application is
  130.     disposed, no need for you to free your objects yourself.
  131.  
  132.     To receive input from your objects, you will also need to
  133.     install a MUIA_Application_BrokerHook.
  134.  
  135.     NOTES
  136.     Unless you have set MUIA_Application_RequiresCX, you must be
  137.     prepared to receive a NULL pointer. In this case, the
  138.     commodities interface is not available, maybe because the
  139.     user installed a light version of MUI.
  140.  
  141.     SEE ALSO
  142.     MUIA_Application_BrokerHook
  143. Application.mui/MUIA_Application_BrokerHook
  144.  
  145.     NAME
  146.     MUIA_Application_BrokerHook -- (V4 ) [ISG], struct Hook *
  147.  
  148.     FUNCTION
  149.     You specify a pointer to hook structure. The function
  150.     will be called whenever a commodities message arrives
  151.     (between MUI's GetMsg() and ReplyMsg()).
  152.  
  153.     You receive a pointer to the application object
  154.     as object in a2 and a pointer to commodities
  155.     CxMsg message in a1.
  156.  
  157.     NOTES
  158.     The commodities interface isn't available in the
  159.     memory saving "light" version of MUI. Your hook
  160.     will never be called in this case.
  161.  
  162.     SEE ALSO
  163.     MUIA_Application_Broker
  164. Application.mui/MUIA_Application_BrokerPort
  165.  
  166.     NAME
  167.     MUIA_Application_BrokerPort -- (V6 ) [..G], struct MsgPort *
  168.  
  169.     FUNCTION
  170.     Get a pointer to the applications commodities message port.
  171.     If you want to add own Hotkeys to your application, you
  172.     need a message port. Instead of creating your own, you
  173.     should better use this one.
  174.  
  175.     NOTES
  176.     Unless you have set MUIA_Application_RequiresCX, you must be
  177.     prepared to receive a NULL pointer. In this case, the
  178.     commodities interface is not available, maybe because the
  179.     user installed a light version of MUI.
  180.  
  181.     SEE ALSO
  182.     MUIA_Application_BrokerHook
  183. Application.mui/MUIA_Application_BrokerPri
  184.  
  185.     NAME
  186.     MUIA_Application_BrokerPri -- (V6 ) [I.G], LONG
  187.  
  188.     FUNCTION
  189.     Adjust the priority of an applications broker.
  190.  
  191.     SEE ALSO
  192.     MUIA_Application_BrokerHook
  193. Application.mui/MUIA_Application_Commands
  194.  
  195.     NAME
  196.     MUIA_Application_Commands -- (V4 ) [ISG], struct MUI_Command *
  197.  
  198.     FUNCTION
  199.     This attribute allows an application to include 
  200.     its own set of ARexx commands. You specify a
  201.     pointer to an array of MUI_Command structures,
  202.     which look like this:
  203.  
  204.     struct MUI_Command
  205.     {
  206.        char        *mc_Name;
  207.        char        *mc_Template;
  208.        LONG         mc_Parameters;
  209.        struct Hook *mc_Hook;
  210.        LONG         mc_Reserved[5];
  211.     };
  212.  
  213.     mc_Name       contains the name of your command.
  214.                   Commands are not case sensitive.
  215.  
  216.     mc_Template   is an argument template that follows
  217.                   the same rules as dos.library/ReadArgs().
  218.                   It may be NULL, in which case your command
  219.                   doesn't need any parameters.
  220.  
  221.     mc_Parameters is the number of parameters specified
  222.                   in the template array.
  223.  
  224.     mc_Hook       is a pointer to the callback hook defining
  225.                   the function to be called.
  226.  
  227.     You may specify any number of MUI_Command structures,
  228.     but you must terminate your array with a NULL field.
  229.  
  230.     When a command shows up an applications ARexx port,
  231.     MUI parses the arguments according to the given
  232.     template and calls the hook with the application
  233.     object as hook object in a2 and a pointer to
  234.     an array of longwords containing the parameters
  235.     in a1.
  236.  
  237.     The result code of your hook will be replied to
  238.     ARexx as rc.
  239.  
  240.     If you have some simple ARexx commands that just
  241.     emulate some user action (e.g. clicking a button),
  242.     you can use the magic cookie MC_TEMPLATE_ID for 
  243.     mc_Template and a return id value for mc_Parameters. 
  244.     In this case, MUI will do no argument parsing and 
  245.     instead simply return the specified id value on the 
  246.     next call to MUIM_Application_Input.
  247.  
  248.     For more sophisticated possibilities in ARexx
  249.     callback hooks, please refer to
  250.     MUIA_Application_RexxMsg and MUIA_Application_RexxString.
  251.  
  252.     EXAMPLE
  253.     static struct MUI_Command commands[] =
  254.     {
  255.        { "rescan", MC_TEMPLATE_ID, ID_RESCAN, NULL     },
  256.        { "select", "PATTERN/A"   , 1        , &selhook },
  257.        { NULL    , NULL          , NULL     , NULL     }
  258.     };
  259.  
  260.     SEE ALSO
  261.     MUIA_Application_RexxMsg, MUIA_Application_RexxString
  262. Application.mui/MUIA_Application_Copyright
  263.  
  264.     NAME
  265.     MUIA_Application_Copyright -- (V4 ) [I.G], STRPTR
  266.  
  267.     FUNCTION
  268.     A copyright string, containing the year and the
  269.     company.
  270.  
  271.     EXAMPLE
  272.     see MUIA_Application_Title
  273.  
  274.     SEE ALSO
  275.     MUIA_Application_Title, MUIA_Application_Version,
  276.     MUIA_Application_Author, MUIA_Application_Description,
  277.     MUIA_Application_Base
  278. Application.mui/MUIA_Application_Description
  279.  
  280.     NAME
  281.     MUIA_Application_Description -- (V4 ) [I.G], STRPTR
  282.  
  283.     FUNCTION
  284.     Short description, about 40 characters.
  285.     Shown e.g. in commodities exchange.
  286.  
  287.     EXAMPLE
  288.     see MUIA_Application_Title
  289.  
  290.     SEE ALSO
  291.     MUIA_Application_Title, MUIA_Application_Version,
  292.     MUIA_Application_Author, MUIA_Application_Copyright,
  293.     MUIA_Application_Base
  294. Application.mui/MUIA_Application_DiskObject
  295.  
  296.     NAME
  297.     MUIA_Application_DiskObject -- (V4 ) [ISG], struct DiskObject *
  298.  
  299.     FUNCTION
  300.     Pointer to a struct DiskObject, e.g. obtained
  301.     from GetDiskObject(). If present, MUI will use
  302.     this object for the AppIcon when your application
  303.     gets iconified.
  304.  
  305.     Otherwise MUI will try to locate "env:sys/dev_mui.info"
  306.     and, if not present, fall back to a default icon.
  307.  
  308.     EXAMPLE
  309.     ...
  310.     MUIA_Application_DiskObject, 
  311.        dobj = GetDiskObject("PROGDIR:MyApp"),
  312.     ...
  313.  
  314.     /* note that you have to free dobj yourself! */
  315.  
  316.     NOTES
  317.     Unless you have set MUIA_Application_RequiresIconification,
  318.     this attribute might have no effect, maybe because the
  319.     user installed a light version of MUI. You must be prepared
  320.     to receive a NULL pointer when you try to read it!
  321.  
  322.    SEE ALSO
  323.     MUIA_Application_Iconified
  324. Application.mui/MUIA_Application_DoubleStart
  325.  
  326.     NAME
  327.     MUIA_Application_DoubleStart -- (V4 ) [..G], BOOL
  328.  
  329.     FUNCTION
  330.     This attribute is set automatically when the user
  331.     tries to start a MUIA_SingleTask application twice.
  332.     You can react on this and take appropriate actions,
  333.     e.g. pop up a requester or quit yourself.
  334.  
  335.     SEE ALSO
  336.     MUIA_Application_SingleTask
  337. Application.mui/MUIA_Application_DropObject
  338.  
  339.     NAME
  340.     MUIA_Application_DropObject -- (V5 ) [IS.], Object *
  341.  
  342.     FUNCTION
  343.     If your application is iconified and the user drops
  344.     icons onto the AppIcon, the object specified here will 
  345.     receive the AppMessage.
  346.  
  347.     SEE ALSO
  348.     MUIA_Window_AppWindow, MUIM_CallHook
  349. Application.mui/MUIA_Application_ForceQuit
  350.  
  351.     NAME
  352.     MUIA_Application_ForceQuit -- (V8 ) [..G], BOOL
  353.  
  354.     FUNCTION
  355.     When your input loop receives a MUIV_Application_ReturnID_Quit,
  356.     you should query this attribute. In case its TRUE, your program
  357.     should exit quietly without popping up any safety requesters or 
  358.     other stuff.
  359.  
  360.     MUI will e.g. set this if the user issued a "QUIT FORCE" ARexx
  361.     command to your application.
  362. Application.mui/MUIA_Application_HelpFile
  363.  
  364.     NAME
  365.     MUIA_Application_HelpFile -- (V8 ) [ISG], STRPTR
  366.  
  367.     FUNCTION
  368.     This attribute allows defining an AmigaGuide style file
  369.     to be displayed when the user requests online help.
  370.  
  371.     When the HELP button is pressed and the application
  372.     defines a MUIA_Application_HelpFile, MUI tries to obtain
  373.     MUIA_HelpNode from the current object (the one under
  374.     the mouse pointer). If MUIA_HelpNode is not defined,
  375.     MUI continues asking the parent object for this
  376.     attribute (usually a group, but remember: the parent
  377.     of a windows root object is the window itself, the
  378.     parent of a window is the application).
  379.  
  380.     When a non NULL MUIA_HelpNode is found, the same procedure
  381.     is applied to MUIA_HelpLIne. Then MUI puts the application 
  382.     to sleep and displays the file at the position specified 
  383.     with MUIA_HelpNode and/or MUIA_HelpLine.
  384.  
  385.     This behaviour allows you to define one 
  386.     MUIA_Application_HelpFile for your application object 
  387.     and different help nodes and lines for your applications 
  388.     windows and/or gadgets.
  389.  
  390.     EXAMPLE
  391.  
  392.     ApplicationObject,
  393.        ...
  394.        MUIA_Application_HelpFile, "progdir:myapp.guide",
  395.        ...,
  396.        SubWindow, WindowObject,
  397.           MUIA_Window_Title, "Prefs Window",
  398.           ...,
  399.           MUIA_HelpNode, "prefs-section",
  400.           ...,
  401.           End,
  402.  
  403.        SubWindow, WindowObject,
  404.           MUIA_Window_Title, "Play Window",
  405.           ...
  406.           MUIA_HelpNode, "play-section",
  407.           ...
  408.           WindowContents, VGroup,
  409.              ...,
  410.              Child, StringObject,
  411.                 MUIA_HelpNode, "play-string",
  412.                 ...,
  413.                 End,
  414.              End,
  415.           End,
  416.        End;
  417.  
  418.     In this case, the user will get the prefs-section chapter
  419.     of "myapp.guide" when he requests help in the Prefs window,
  420.     the play-string chapter when he requests help over the
  421.     string gadget in the Play window or the play-section
  422.     chapter somewhere else in the Play window.
  423.  
  424.     NOTES
  425.     Since muimaster.library V8, this attribute replaces the old
  426.     and obsolete MUIA_HelpFile attribute. MUI no longer supports
  427.     the possibility to specify different help files for different
  428.     parts of your application. This step was necessary due to
  429.     some other internal changes and enhancements.
  430.  
  431.     SEE ALSO
  432.     MUIA_HelpNode, MUIA_HelpLine
  433. Application.mui/MUIA_Application_Iconified
  434.  
  435.     NAME
  436.     MUIA_Application_Iconified -- (V4 ) [.SG], BOOL
  437.  
  438.     FUNCTION
  439.     Setting this attribute to TRUE causes the application
  440.     to become iconified. Every open window will be closed
  441.     and a (configurable) AppIcon will appear on the workbench.
  442.  
  443.     Same thing happens when the user hits the iconify gadget
  444.     in the window border or uses commodities Exchange to
  445.     hide your applications interface.
  446.  
  447.     There is no way for you to prevent your application from
  448.     being iconified. However, you can react on the iconification
  449.     by listening to the MUIA_Application_Iconified attribute
  450.     with notification. This allows you to free some resources
  451.     you don't need in iconified state.
  452.  
  453.     When an application is iconified and you try to open a
  454.     window, the window won't open immediately. Instead MUI
  455.     remembers this action and opens the window once the
  456.     application is uniconified again.
  457.  
  458.     EXAMPLE
  459.  
  460.     /* inform the main input loop of iconification events */
  461.  
  462.     #define ID_HIDE 42
  463.     #define ID_SHOW 24
  464.  
  465.     DoMethod(app,MUIM_Notify,
  466.        MUIA_Application_Iconified, TRUE,
  467.        app, 2, MUIM_Application_ReturnID, ID_HIDE);
  468.  
  469.     DoMethod(app,MUIM_Notify,
  470.        MUIA_Application_Iconified, FALSE,
  471.        app, 2, MUIM_Application_ReturnID, ID_SHOW);
  472.  
  473.     SEE ALSO
  474.     MUIA_Application_DiskObject
  475. Application.mui/MUIA_Application_Menu
  476.  
  477.     NAME
  478.     MUIA_Application_Menu -- (V4 ) [I.G], struct NewMenu * (OBSOLETE)
  479.  
  480.     FUNCTION
  481.     Obsolete, use MUIA_Application_Menustrip instead.
  482.  
  483.     SEE ALSO
  484.     MUIA_Application_Menustrip
  485. Application.mui/MUIA_Application_MenuAction
  486.  
  487.     NAME
  488.     MUIA_Application_MenuAction -- (V4 ) [..G], ULONG
  489.  
  490.     FUNCTION
  491.     Whenever a menu item is selected, this attribute will be
  492.     set to the corresponding UserData field of the gadtools
  493.     NewMenu structure. This allows reacting on menu items
  494.     via broadcasting.
  495.  
  496.     SEE ALSO
  497.     MUIA_Application_Menu, MUIA_Application_MenuAction
  498. Application.mui/MUIA_Application_MenuHelp
  499.  
  500.     NAME
  501.     MUIA_Application_MenuHelp -- (V4 ) [..G], ULONG
  502.  
  503.     FUNCTION
  504.     Whenever a menu item is selected with the help key, this
  505.     attribute will be set to the corresponding UserData field
  506.     of the gadtools NewMenu structure. Together with
  507.     MUIM_Application_ShowHelp this allows creation of
  508.     menu help texts.
  509.  
  510.     SEE ALSO
  511.     MUIA_Application_Menu, MUIA_Application_ShowHelp
  512. Application.mui/MUIA_Application_Menustrip
  513.  
  514.     NAME
  515.     MUIA_Application_Menustrip -- (V8 ) [I..], Object *
  516.  
  517.     FUNCTION
  518.     Specify a menu strip object for the application. The object
  519.     is treated as a child of the application and will be disposed
  520.     when the application is disposed.
  521.  
  522.     Menustrip objects defined for the application are used
  523.     as menu for every window of the application, as long as
  524.     the window doesn't define its private menu.
  525.  
  526.     MUIA_Application_Menustrip replaces the old and obsolete
  527.     MUIA_Application_Menu tag.
  528.  
  529.     Usually, you will create the menu object with MUI's builtin
  530.     object library from a gadtools NewMenu structure, but its
  531.     also OK to define the menu tree "by hand" using the
  532.     Family class.
  533. Application.mui/MUIA_Application_RexxHook
  534.  
  535.     NAME
  536.     MUIA_Application_RexxHook -- (V7 ) [ISG], struct Hook *
  537.  
  538.     FUNCTION
  539.     When specified, MUI calls this hook whenever a rexx message 
  540.     arrives and MUI can't map it to a builtin or a programmer
  541.     specified command. The hook will be called with a pointer 
  542.     to itself in A0, a pointer to the application object in A2 
  543.     and a pointer to a struct RexxMsg in A1.
  544.  
  545.     The return code from the hook is used as result code
  546.     when replying the message, the secondary result can
  547.     be set with MUIA_Application_RexxString.
  548.  
  549.     SEE ALSO
  550.     MUIA_Application_Commands
  551. Application.mui/MUIA_Application_RexxMsg
  552.  
  553.     NAME
  554.     MUIA_Application_RexxMsg -- (V4 ) [..G], struct RxMsg *
  555.  
  556.     FUNCTION
  557.     Within an ARexx callback hook, you can obtain
  558.     a pointer to the RexxMsg that came with the
  559.     command. This allows you to use some ARexx
  560.     support functions coming with amiga.lib
  561.  
  562.     SEE ALSO
  563.     MUIA_Application_Commands, MUIA_Application_RexxString
  564. Application.mui/MUIA_Application_RexxString
  565.  
  566.     NAME
  567.     MUIA_Application_RexxString -- (V4 ) [.S.], STRPTR
  568.  
  569.     FUNCTION
  570.     ARexx allows returning a string as result of a
  571.     function call. This attribute allows setting the
  572.     result string within an ARexx callback hook.
  573.  
  574.     The string is temporarily copied.
  575.  
  576.     SEE ALSO
  577.     MUIA_Application_Commands, MUIA_Application_RexxMsg
  578. Application.mui/MUIA_Application_SingleTask
  579.  
  580.     NAME
  581.     MUIA_Application_SingleTask -- (V4 ) [I..], BOOL
  582.  
  583.     FUNCTION
  584.     Boolean value to indicate whether or not your application
  585.     is a single task program. When set to TRUE, MUI will
  586.     refuse to create more than one application object.
  587.  
  588.     In this case, the already running application gets its
  589.     MUIA_DoubleStart attribute set to TRUE. You can listen
  590.     to this and take appropriate actions, e.g. pop up
  591.     a requester.
  592.  
  593.     Examples for single task applications are the system
  594.     preferences program. It doesn't make sense for them
  595.     to run more than once.
  596.  
  597.     SEE ALSO
  598.     MUIA_Application_DoubleStart
  599. Application.mui/MUIA_Application_Sleep
  600.  
  601.     NAME
  602.     MUIA_Application_Sleep -- (V4 ) [.S.], BOOL
  603.  
  604.     FUNCTION
  605.     This attribute can be used to put a whole application
  606.     to sleep. All open windows get disabled and a busy
  607.     pointer appears.
  608.  
  609.     This attribute contains a nesting count, if you tell
  610.     your application to sleep twice, you will have to tell 
  611.     it to wake up twice too.
  612.  
  613.     If you need to do some time consuming actions, you
  614.     always should set this attribute to inform the user
  615.     that you are currently unable to handle input.
  616.  
  617.     A sleeping application's windows cannot be resized.
  618.  
  619.     EXAMPLES
  620.     set(app,MUIA_Application_Sleep,TRUE ); // go to bed
  621.     calc_fractals();
  622.     set(app,MUIA_Application_Sleep,FALSE); // wake up
  623.  
  624.     SEE ALSO
  625.     MUIA_Window_Sleep, MUIM_Application_InputBuffered
  626. Application.mui/MUIA_Application_Title
  627.  
  628.     NAME
  629.     MUIA_Application_Title -- (V4 ) [I.G], STRPTR
  630.  
  631.     FUNCTION
  632.     This tag defines the title of an application.
  633.     The title is e.g. shown in Commodities Exchange
  634.     or in the MUI preferences program.
  635.  
  636.     An application title shall not contain any version
  637.     information, just the pure title. Also, special
  638.     characters such as ":/()#?*..." are not allowed.
  639.  
  640.     You should use a quiet long and unique name for
  641.     your applications. Naming it "Viewer" or "Browser"
  642.     is not a wise choice.
  643.  
  644.     The length of the name must not exceed 30 characters!
  645.  
  646.     EXAMPLE
  647.     ApplicationObject,
  648.        MUIA_Application_Title      , "WbMan",
  649.        MUIA_Application_Version    , "$VER: WbMan 0.24 (19.7.93)",
  650.        MUIA_Application_Copyright  , "© 1993 by Klaus Melchior",
  651.        MUIA_Application_Author     , "Klaus Melchior",
  652.        MUIA_Application_Description, "Manages the WBStartup.",
  653.        MUIA_Application_Base       , "WBMAN",
  654.        ...
  655.  
  656.     SEE ALSO
  657.     MUIA_Application_Version, MUIA_Application_Copyright,
  658.     MUIA_Application_Author, MUIA_Application_Description,
  659.     MUIA_Application_Base
  660. Application.mui/MUIA_Application_UseCommodities
  661.  
  662.     NAME
  663.     MUIA_Application_UseCommodities -- (V10) [I..], BOOL
  664.  
  665.     FUNCTION
  666.     When set to FALSE, the application will run without a 
  667.     commodities interface. Think very well before using this
  668.     tag!
  669.  
  670.     SEE ALSO
  671.         MUIA_Application_UseRexx
  672. Application.mui/MUIA_Application_UseRexx
  673.  
  674.     NAME
  675.     MUIA_Application_UseRexx -- (V10) [I..], BOOL
  676.  
  677.     FUNCTION
  678.     When set to FALSE, the application will run without an
  679.     ARexx interface. Think very well before using this
  680.     tag!
  681.  
  682.     SEE ALSO
  683.         MUIA_Application_UseCommodities
  684. Application.mui/MUIA_Application_Version
  685.  
  686.     NAME
  687.     MUIA_Application_Version -- (V4 ) [I.G], STRPTR
  688.  
  689.     FUNCTION
  690.     Define a version string for an application.
  691.     This string shall follow standard version string
  692.     convetions but must *not* contain a leading "\0".
  693.  
  694.     EXAMPLE
  695.     see MUIA_Application_Title
  696.  
  697.     SEE ALSO
  698.     MUIA_Application_Title, MUIA_Application_Copyright,
  699.     MUIA_Application_Author, MUIA_Application_Description,
  700.     MUIA_Application_Base
  701. Application.mui/MUIA_Application_Window
  702.  
  703.     NAME
  704.     MUIA_Application_Window -- (V4 ) [I..], Object *
  705.  
  706.     FUNCTION
  707.     A pointer to a MUI object of Window class. An
  708.     application may have any number of sub windows,
  709.     each of them being a child of the application.
  710.  
  711.     When the application receives some kind of user
  712.     input through its IDCMP, it diverts the message
  713.     down to its children, as long as they are opened.
  714.  
  715.     Things like iconification or preferences changes
  716.     cause the application object to temporarily close
  717.     every open window (and reopen it later). Your
  718.     main program normally doesn't need to deal with
  719.     these things.
  720.  
  721.     As with the children of group class, it's common
  722.     to use a call to MUI_NewObject() as value for
  723.     this attribute. No error checking needs to be
  724.     done, the application object handles every
  725.     failure automatically.
  726.  
  727.     When you dispose your application, its sub windows
  728.     will also get deleted. Thus, the only thing to do
  729.     to remove your application is a
  730.  
  731.     MUI_DisposeObject(ApplicationObject);
  732.  
  733.     Every window, every gadget, every memory will be
  734.     freed by this single call.
  735.  
  736.     EXAMPLE
  737.     Please refer to one of the example programs.
  738.  
  739.     SEE ALSO
  740. Application.mui/MUIM_Application_AddInputHandler
  741.  
  742.     NAME
  743.     MUIM_Application_AddInputHandler (V11)
  744.  
  745.     SYNOPSIS
  746.     DoMethod(obj,MUIM_Application_AddInputHandler,struct MUI_InputHandlerNode *ihnode);
  747.  
  748.     FUNCTION
  749.     Up to MUI 2.3, it was not easy to build custom classes which
  750.     should react on signals of private message ports. For example,
  751.     a clock class would want to be notified every second to update
  752.     its display. Old versions of MUI forced you to Wait() for
  753.     a timer signal in the main loop and notify the custom class.
  754.  
  755.     Since MUI 3, the existance of so called "input handlers"
  756.     (don't mix up with input.device input handler) eliminates
  757.     the need of dealing with the main loop in these cases.
  758.     A class can create message ports and react on their
  759.     signals on its own without interferring the main program.
  760.  
  761.     For a clock class, this would mean that you simply create
  762.     the object into any MUI window and it starts updating
  763.     itself every second automatically. A game class could open
  764.     the gameport.device and react on joystick messages, an
  765.     html class could talk to network ports all on its own.
  766.  
  767.     All this helps to further encapsulate your program into
  768.     subclasses and make it a lot more easy to maintain. Let
  769.     me repeat the main loop of an ideal MUI application here:
  770.  
  771.     ULONG sigs = 0;
  772.  
  773.     while (DoMethod(app,MUIM_Application_NewInput,&sigs)
  774.            != MUIV_Application_ReturnID_Quit)
  775.     {
  776.         if (sigs)
  777.         {
  778.             sigs = Wait(sigs | SIGBREAKF_CTRL_C);
  779.             if (sigs & SIGBREAKF_CTRL_C) break;
  780.         }
  781.     }
  782.  
  783.     To be able to react on signals, you must fill out a
  784.     MUI_InputHandlerNode structure (probably located in
  785.     your classes instance data) and call
  786.     MUIM_Application_AddInputHandler with the structure
  787.     as parameter. From now on, your class will receive
  788.     the specified method whenever one of the given signals
  789.     arrives.
  790.  
  791.     Since we're talking about a method of application
  792.     class here, it's clear that you cannot call it until
  793.     you know about your application object. Good places
  794.     for MUIM_Application_AddInputHandler/RemInputHandler
  795.     are probably the MUIM_Setup/MUIM_Cleanup methods
  796.     of your class.
  797.  
  798.     INPUTS
  799.     ihnode - Pointer to an initialized MUI_InputHandlerNode
  800.              structure:
  801.              ihn_Object  - fill in a pointer to your object.
  802.              ihn_Signals - signals you wish to be notified on.
  803.                            You can set more than one bit here.
  804.              ihn_Flags   - always set to 0 for now.
  805.              ihn_Method  - method that you want to receive
  806.                            when one of ihn_Signals is set.
  807.  
  808.     RESULT
  809.     MUIM_Application_AddInputHandler cannot fail, the result
  810.     value of the method is currently undefined.
  811.  
  812.     NOTES
  813.     You must match each AddInputHandler with exatly
  814.     one RemInputHandler method. Do not add a
  815.     MUI_InputHandlerNode which is currently in use.
  816.  
  817.     IMPORTANT: Your trigger method might also be
  818.     called when none of your signals arrived. You *must*
  819.     make sure that you check your conditions in
  820.     the trigger method (if (GetMsg(port) ... or
  821.     if (CheckIO(req)) ...). Also, please make these
  822.     checks quick and return FALSE as fast as possible
  823.     when none of your conditions was met. Return TRUE
  824.     if you have "used" the trigger method.
  825.  
  826.     EXAMPLE
  827.     OM_NEW:
  828.        data->port = CreateMsgPort();
  829.        data->req = CreateIORequest(data->port,sizeof(struct timer));
  830.        OpenDevice(TIMERNAME,UNIT_VBLANK,(struct IORequest *)data->req,0);
  831.        data->ihnode.ihn_Object  = obj;
  832.        data->ihnode.ihn_Signals = IO_SIGMASK(data->req);
  833.        data->ihnode.ihn_Flags   = 0;
  834.        data->ihnode.ihn_Method  = MY_TRIGGER_METHOD;
  835.  
  836.     OM_DISPOSE:
  837.        CloseDevice((struct IORequest *)data->req);
  838.        DeleteIORequest(data->req);
  839.        DeleteMsgPort(data->port);
  840.  
  841.     MUIM_Setup:
  842.        data->req->tr_node.io_Command = TR_ADDREQUEST;
  843.        data->req->tr_time.tv_secs    = 1;
  844.        data->req->tr_time.tv_micro   = 0;
  845.        SendIO((struct IORequest *)data->req);
  846.        DoMethod(_app(obj),MUIM_Application_AddInputHandler,&data->ihnode);
  847.  
  848.     MUIM_Cleanup:
  849.        DoMethod(_app(obj),MUIM_Application_RemInputHandler,&data->ihnode);
  850.        if (!CheckIO(data->req)) AbortIO(data->req);
  851.        WaitIO(data->req);
  852.  
  853.     MY_TRIGGER_METHOD:
  854.        if (CheckIO(data->req))
  855.        {
  856.           WaitIO(data->req);
  857.  
  858.           /* update display or do anything else here ... */
  859.  
  860.           /* send a new timer event */
  861.           data->req->tr_node.io_Command = TR_ADDREQUEST;
  862.           data->req->tr_time.tv_secs    = 1;
  863.           data->req->tr_time.tv_micro   = 0;
  864.           SendIO((struct IORequest *)data->req);
  865.  
  866.           return(TRUE);
  867.        }
  868.        return(FALSE);
  869.  
  870.     SEE ALSO
  871.     MUIM_Application_RemInputHandler, MUIM_Application_Input
  872. Application.mui/MUIM_Application_CheckRefresh
  873.  
  874.     NAME
  875.     MUIM_Application_CheckRefresh (V11)
  876.  
  877.     SYNOPSIS
  878.     DoMethod(obj,MUIM_Application_CheckRefresh,);
  879.  
  880.     FUNCTION
  881.     This method checks all currently open windows if they
  882.     need refreshing and refreshes them if necessary.
  883.  
  884.     You won't need to call this method if you are within
  885.     your traditional MUI main loop. However, if you e.g.
  886.     spawn some kind of synchronous requester (AslRequest),
  887.     MUI cannot react on IDCMP_REFRESHWINDOW messages.
  888.  
  889.     The result is that the user may see a damaged MUI window
  890.     if he moves around a file requester and MUI is configured
  891.     for simple refresh.
  892.  
  893.     MUIA_Application_CheckRefresh is the solution for this
  894.     problem. Just open your requesters with
  895.  
  896.     ASLFR_UserData    , ApplicationObject,
  897.     ASLFR_IntuiMsgFunc, &IntuiMsgHook,
  898.  
  899.     and let IntuiMsgHook point to something like this:
  900.  
  901.     SAVEDS ASM VOID IntuiMsgFunc(
  902.        _a1 struct IntuiMessage *imsg,
  903.        _a2 struct FileRequester *req)
  904.     {
  905.        if (imsg->Class==IDCMP_REFRESHWINDOW)
  906.           DoMethod(req->fr_UserData,MUIM_Application_CheckRefresh);
  907.     }
  908.  
  909.     RESULT
  910.     Windows with damage will be refreshed. This may result in
  911.     MUI calling MUIM_Draw of some of your custom classes.
  912.     The result value of this method is undefined.
  913.  
  914.     SEE ALSO
  915.     MUIM_Application_InputBuffered
  916. Application.mui/MUIM_Application_GetMenuCheck
  917.  
  918.     NAME
  919.     MUIM_Application_GetMenuCheck (V4 ) (OBSOLETE)
  920.  
  921.     SYNOPSIS
  922.     DoMethod(obj,MUIM_Application_GetMenuCheck,ULONG MenuID);
  923.  
  924.     FUNCTION
  925.     Ask whether a checkmark menu item has its checkmark
  926.     set or cleared.
  927.     The application will ask its sub windows for a
  928.     menu item with the given id and return the state of
  929.     the first item it finds.
  930.  
  931.     INPUTS
  932.     MenuID - the value you wrote into the
  933.                  UserData field of struct NewMenu.
  934.  
  935.     SEE ALSO
  936.     MUIM_Application_SetMenuCheck, MUIA_Application_Menu
  937. Application.mui/MUIM_Application_GetMenuState
  938.  
  939.     NAME
  940.     MUIM_Application_GetMenuState (V4 ) (OBSOLETE)
  941.  
  942.     SYNOPSIS
  943.     DoMethod(obj,MUIM_Application_GetMenuState,ULONG MenuID);
  944.  
  945.     FUNCTION
  946.     Ask whether a menu item is enabled or disabled.
  947.     The application will ask its sub windows for a
  948.     menu item with the given id and return the state of
  949.     the first item it finds.
  950.  
  951.     INPUTS
  952.     MenuID - the value you wrote into the
  953.                  UserData field of struct NewMenu.
  954.  
  955.     SEE ALSO
  956.     MUIM_Application_SetMenuState, MUIA_Application_Menu
  957. Application.mui/MUIM_Application_Input
  958.  
  959.     NAME
  960.     MUIM_Application_Input (V4 ) (OBSOLETE)
  961.  
  962.     SYNOPSIS
  963.     DoMethod(obj,MUIM_Application_Input,LONGBITS *signal);
  964.  
  965.     FUNCTION
  966.     The MUI system itself does not wait for any user input.
  967.     It just tells your application which signal bits it
  968.     has allocated, then it's up to you to call MUIs input
  969.     handle function when one of these signals gets set.
  970.  
  971.     In a simple MUI application you would just Wait()
  972.     for these signals and call MUI when one is received.
  973.     However, you can perfectly allocate some signal bits
  974.     yourself and include them in your Wait() command.
  975.     You needn't even Wait(), your application could
  976.     maybe calculate some fractal graphics or copy
  977.     disks, the only important thing is that you call
  978.     MUI's input method when one of the MUI allocated
  979.     signals arrives.
  980.  
  981.     The usual way of communication with your user
  982.     interface is via return ids. Every action happening
  983.     to the GUI can create return ids, e.g. pressing a
  984.     button or trying to close a window. MUI buffers these
  985.     ids and uses them as result codes for the input method.
  986.     Thats where you can get it from and take the appropriate
  987.     actions.
  988.  
  989.     Now lets have a look on a usual input loop of a
  990.     MUI application. Imagine you have an Play and a
  991.     Cancel button and have previously told them
  992.     to return ID_PLAY and ID_CANCEL when pressed.
  993.     (see MUIM_Notify and MUIM_Application_ReturnID
  994.     on information about these topics). Your input
  995.     loop would look like this:
  996.  
  997.  
  998.     while (running)
  999.     {
  1000.        ULONG signals;
  1001.  
  1002.        switch (DoMethod(app,MUIM_Application_Input,&signals))
  1003.        {
  1004.           case ID_PLAY:
  1005.              PlaySound();
  1006.              break;
  1007.  
  1008.           case ID_CANCEL:
  1009.           case MUIV_Application_ReturnID_Quit:
  1010.              running = FALSE;
  1011.              break;
  1012.        }
  1013.  
  1014.        if (running && signals) Wait(signals);
  1015.     }
  1016.  
  1017.  
  1018.     So what is happening here?
  1019.  
  1020.     First, you have to call the MUIM_Application_Input method.
  1021.     You supply the address of a ULONG as parameter, thats
  1022.     where MUI fills in the signals it needs. Note that you can
  1023.     call the input method at any time, regardless of signal
  1024.     setting. MUI will simply return when there is nothing
  1025.     to do.
  1026.  
  1027.     In case the user pressed the Play or the Cancel button,
  1028.     MUIM_Application_Input will return ID_PLAY or ID_CANCEL.
  1029.     Otherwise you will receive a 0, that's why you cannot
  1030.     use 0 as one of your id values.
  1031.  
  1032.     There is one predefined id called
  1033.     MUIV_Application_ReturnID_Quit. This will be sent to you
  1034.     when someone tried to quit your application from outside,
  1035.     e.g. via commodities exchange or the ARexx "quit" command.
  1036.     It is required that your application handles this id,
  1037.     just treat as if the user clicked on a "Quit" button or
  1038.     selected a "Quit" menu item.
  1039.  
  1040.     After handling the return value, you have to examine
  1041.     if MUI wants you to wait for any signals. If this
  1042.     is the case (signals != 0), just wait for it. If
  1043.     MUI puts a 0 into signals it wants to tell you to
  1044.     immediately call the input method again, maybe some
  1045.     other return ids have received and need to be handled.
  1046.     You *must* check this because Wait()ing on a zero
  1047.     signal mask is not a good idea!
  1048.  
  1049.     Note: It is very important that you call the input method
  1050.     whenever a signal arrives. MUI needs this to correctly
  1051.     refresh its windows, handle resizing and iconification
  1052.     operations and commodities and ARexx messages. If you
  1053.     don't, you will annoy your user!
  1054.  
  1055.     If your program needs to be in a state where you are
  1056.     for some reasons unable to call the input method for
  1057.     a considerable amount of time (maybe half a second or
  1058.     more), you should put your application to sleep. See
  1059.     MUIA_Application_Sleep on how to do this.
  1060.  
  1061.     SEE ALSO
  1062.     MUIA_Application_Sleep, MUIM_Application_InputBuffered,
  1063.     MUIM_Application_NewInput
  1064. Application.mui/MUIM_Application_InputBuffered
  1065.  
  1066.     NAME
  1067.     MUIM_Application_InputBuffered (V4 )
  1068.  
  1069.     SYNOPSIS
  1070.     DoMethod(obj,MUIM_Application_InputBuffered,);
  1071.  
  1072.     FUNCTION
  1073.     Imagine your application does some time consuming
  1074.     operation, e.g. copying a disk, and you are for
  1075.     some reasons unable to react on return ids during
  1076.     this period. One solution would be to simply
  1077.     put your application to sleep, it will get a
  1078.     busy pointer and the user knows whats going on.
  1079.  
  1080.     However, this will make it impossible for the user
  1081.     to resize your applications windows or iconify it,
  1082.     he will have to wait until you are done with your
  1083.     operation.
  1084.  
  1085.     MUIM_Application_InputBuffered offers a solution
  1086.     for this problem. Using this method, you needn't
  1087.     set to sleep your application. Just call it on a
  1088.     regular basis and MUI will be able to handle
  1089.     all actions concerning the GUI. You do not need
  1090.     to pay attention on return values, they remain
  1091.     on an internal stack until your next call to
  1092.     the non buffered input method.
  1093.  
  1094.     EXAMPLE
  1095.     for (track=0; track<80; track++)
  1096.     {
  1097.        read_track();
  1098.        DoMethod(app,MUIM_Application_InputBuffered);
  1099.        write_track();
  1100.        DoMethod(app,MUIM_Application_InputBuffered);
  1101.     }
  1102.  
  1103.     SEE ALSO
  1104.     MUIM_Application_Input, MUIA_Application_Sleep
  1105. Application.mui/MUIM_Application_Load
  1106.  
  1107.     NAME
  1108.     MUIM_Application_Load (V4 )
  1109.  
  1110.     SYNOPSIS
  1111.     DoMethod(obj,MUIM_Application_Load,STRPTR name);
  1112.  
  1113.     FUNCTION
  1114.     MUIM_Application_Save, MUIM_Application_Load and
  1115.     MUIA_ObjectID offer an easy way of saving and loading
  1116.     a programs configuration.
  1117.  
  1118.     Each gadget with a non NULL MUIA_ObjectID will get
  1119.     its contents saved during MUIM_Application_Save and
  1120.     restored during MUIM_Application_Load. This makes
  1121.     it very easy to design a configuration window
  1122.     with "Save", "Use" and "Cancel" buttons to allow
  1123.     the user storing the settings. When the application
  1124.     starts, you would just have to call MUIM_Application_Load
  1125.     and the stored settings will be read and installed.
  1126.  
  1127.     Not all classes are able to import and export their
  1128.     contents. Currently, you may define MUIA_ObjectIDs for
  1129.  
  1130.     String class   - MUIA_String_Contents is ex/imported.
  1131.     Radio class    - MUIA_Radio_Active is ex/imported.
  1132.     Cycle class    - MUIA_Cycle_Active is ex/imported.
  1133.     List class     - MUIA_List_Active is /ex/imported.
  1134.     Text class     - MUIA_Text_Contents is ex/imported.
  1135.     Slider class   - MUIA_Slider_Level is ex/imported.
  1136.     Area class     - MUIA_Selected is ex/imported
  1137.                      (e.g. for Checkmark gadgets)
  1138.    Menuitem class - MUIA_Checked is ex/imported (V9).
  1139.     Group class    - MUIA_Group_ActivePage is ex/imported (V8).
  1140.  
  1141.     INPUTS
  1142.     name - Name of the file you wish to load the settings from.
  1143.            Usually you won't need to think of a real name but
  1144.            instead use one of the magic cookies
  1145.            MUIV_Application_Load_ENV or
  1146.            MUIV_Application_Load_ENVARC.
  1147.  
  1148.     EXAMPLE
  1149.     see the sample program "Settings.c"
  1150.  
  1151.     SEE ALSO
  1152.     MUIM_Application_Save, notify.mui/MUIA_ObjectID
  1153. Application.mui/MUIM_Application_NewInput
  1154.  
  1155.     NAME
  1156.     MUIM_Application_NewInput (V11)
  1157.  
  1158.     SYNOPSIS
  1159.     DoMethod(obj,MUIM_Application_NewInput,LONGBITS *signal);
  1160.  
  1161.     FUNCTION
  1162.     This is an enhanced replacement for MUIM_Application_Input.
  1163.     It depends on receiving the return value from your Wait()
  1164.     or 0 as input to be able to perform the necessary actions
  1165.     more efficient.
  1166.  
  1167.     MUIM_Application_NewInput is generally preferrable over
  1168.     MUIM_Application_Input.
  1169.  
  1170.     EXAMPLE
  1171.     /*
  1172.     ** This is the ideal input loop for an object oriented MUI
  1173.     ** application. Everything is encapsulated in classes, no
  1174.     ** return ids need to be used, we just check if the program
  1175.     ** shall terminate.
  1176.     ** Note that MUIM_Application_NewInput expects sigs to
  1177.     ** contain the result from Wait() (or 0). This makes the
  1178.     ** input loop significantly faster.
  1179.     */
  1180.  
  1181.     {
  1182.        ULONG sigs = 0;
  1183.  
  1184.        while (DoMethod(app,MUIM_Application_NewInput,&sigs)
  1185.               !=MUIV_Application_ReturnID_Quit)
  1186.        {
  1187.           if (sigs)
  1188.           {
  1189.              sigs = Wait(sigs | SIGBREAKF_CTRL_C);
  1190.              if (sigs & SIGBREAKF_CTRL_C) break;
  1191.           }
  1192.        }
  1193.     }
  1194.  
  1195.     SEE ALSO
  1196.     MUIM_Application_Input
  1197.  
  1198. Application.mui/MUIM_Application_OpenConfigWindow
  1199.  
  1200.     NAME
  1201.     MUIM_Application_OpenConfigWindow (V11)
  1202.  
  1203.     SYNOPSIS
  1204.     DoMethod(obj,MUIM_Application_OpenConfigWindow,ULONG flags);
  1205.  
  1206.     FUNCTION
  1207.     Since MUI 3, applications can open their own MUI configuration
  1208.     window to allow users to adjust the local preferences without
  1209.     the need of an external program. Programmers are supposed to
  1210.     include a "Settings/MUI..." menu item which simply calls
  1211.     MUIM_Application_OpenConfigWindow. MUI will then automatically
  1212.     show the preferences window without blocking the rest of the
  1213.     program.
  1214.  
  1215.     Currently no flags are defined; pass 0 for the time being.
  1216. Application.mui/MUIM_Application_PushMethod
  1217.  
  1218.     NAME
  1219.     MUIM_Application_PushMethod (V4 )
  1220.  
  1221.     SYNOPSIS
  1222.     DoMethod(obj,MUIM_Application_PushMethod,Object *dest, LONG count, /* ... */);
  1223.  
  1224.     FUNCTION
  1225.     Usually, you may not talk to the MUI system from two
  1226.     tasks at the same time. MUIM_Application_PushMethod
  1227.     provides some kind of solution for this problem.
  1228.  
  1229.     This (and only this) method may be called from a
  1230.     second task. It takes another method as parameter
  1231.     and puts in onto a private stack of the application
  1232.     object. The next time MUIM_Application_Input
  1233.     is called, the pushed method will be executed
  1234.     in the context of the current task.
  1235.  
  1236.     INPUTS
  1237.     dest  - object on which to perform the pushed method.
  1238.         count - number of following arguments.
  1239.     ...   - the destination method.
  1240.  
  1241.     RESULT
  1242.     TRUE if successful, FALSE otherwise.
  1243.  
  1244.     EXAMPLE
  1245.     /* set a status line from a sub task */
  1246.     DoMethod(app,MUIM_Application_PushMethod,
  1247.        txstatus,3,MUIM_Set,MUIA_Text_Contents,"reading...");
  1248.  
  1249.     NOTE
  1250.     MUIM_Application_PushMethod has a limit of 7 arguments!
  1251.  
  1252.     SEE ALSO
  1253.     MUIM_Application_Input
  1254. Application.mui/MUIM_Application_RemInputHandler
  1255.  
  1256.     NAME
  1257.     MUIM_Application_RemInputHandler (V11)
  1258.  
  1259.     SYNOPSIS
  1260.     DoMethod(obj,MUIM_Application_RemInputHandler,struct MUI_InputHandlerNode *ihnode);
  1261.  
  1262.     FUNCTION
  1263.     Remove an input handler.
  1264.     MUI will no longer call your trigger method after you have
  1265.     removed the MUI_InputHandlerNode. You can add/remove
  1266.     input handler nodes any time as long as you know
  1267.     about your application object.
  1268.  
  1269.     RESULT
  1270.     MUIM_Application_RemInputHandler cannot fail, the result
  1271.     value of the method is currently undefined.
  1272.  
  1273.     INPUTS
  1274.     ihnode - input handler node structure you passed to
  1275.              MUIM_AddInputHandler previously.
  1276.  
  1277.     SEE ALSO
  1278.     MUIM_Application_AddInputHandler, MUIM_Application_Input
  1279. Application.mui/MUIM_Application_ReturnID
  1280.  
  1281.     NAME
  1282.     MUIM_Application_ReturnID (V4 )
  1283.  
  1284.     SYNOPSIS
  1285.     DoMethod(obj,MUIM_Application_ReturnID,ULONG retid);
  1286.  
  1287.     FUNCTION
  1288.     Tell MUI to return the given id with the next call to 
  1289.     MUIM_Application_Input.
  1290.  
  1291.     Together with the MUI's notification mechanism, this
  1292.     method connects your user interface and your program.
  1293.     If you e.g. want to be informed if the user presses
  1294.     a "Play" button, you would have define an id for
  1295.     this action and set up a notification event with
  1296.     MUIM_Notify.
  1297.  
  1298.     You can use any long word as return id, except
  1299.     from -255 up to 0. These values are reserved for
  1300.     MUI's internal use and for special return values
  1301.     like MUIV_Application_ReturnID_Quit.
  1302.  
  1303.     Note that MUI will put all incoming return ids
  1304.     onto a private fifo stack and feed this stack
  1305.     to its input methods result code later.
  1306.  
  1307.     NOTE
  1308.     The usage of ReturnIDs is no good MUI programming style.
  1309.     You should build your application with sub classes and
  1310.     hooks instead! See the PublicScreenManager source code
  1311.     for an example of good MUI programming!
  1312.  
  1313.     EXAMPLE
  1314.  
  1315.     /* inform me if a button is pressed (actually released, */
  1316.     /* since this is the way amiga buttons are handled)     */
  1317.  
  1318.     #define ID_PLAYBUTTON 42
  1319.  
  1320.     ...
  1321.  
  1322.     DoMethod(buttonobj, MUIM_Notify,
  1323.        MUIA_Pressed, FALSE,
  1324.        appobj, 2, MUIM_Application_ReturnID, ID_PLAYBUTTON);
  1325.  
  1326.     ...
  1327.  
  1328.     while (running)
  1329.     {
  1330.        switch (DoMethod(appobj,MUIM_Application_Input,&sigs))
  1331.        {
  1332.           case ID_PLAYBUTTON:
  1333.              printf("Ok, lets play a game...");
  1334.              break;
  1335.        }
  1336.     }
  1337.  
  1338.     SEE ALSO
  1339.     MUIM_Application_Input, MUIM_Notify
  1340. Application.mui/MUIM_Application_Save
  1341.  
  1342.     NAME
  1343.     MUIM_Application_Save (V4 )
  1344.  
  1345.     SYNOPSIS
  1346.     DoMethod(obj,MUIM_Application_Save,STRPTR name);
  1347.  
  1348.     FUNCTION
  1349.     MUIM_Application_Save, MUIM_Application_Load and
  1350.     MUIA_ObjectID offer an easy way of saving and loading
  1351.     a programs configuration.
  1352.  
  1353.     Each gadget with a non NULL MUIA_ObjectID will get
  1354.     its contents saved during MUIM_Application_Save and
  1355.     restored during MUIM_Application_Load. This makes
  1356.     it very easy to design a configuration window
  1357.     with "Save", "Use" and "Cancel" buttons to allow
  1358.     the user storing the settings. When the application
  1359.     starts, you would just have to call MUIM_Application_Load
  1360.     and the stored settings will be read and installed.
  1361.  
  1362.     Not all classes are able to import and export their
  1363.     contents. Currently, you may define MUIA_ObjectIDs for
  1364.  
  1365.     String class   - MUIA_String_Contents is ex/imported.
  1366.     Radio class    - MUIA_Radio_Active is ex/imported.
  1367.     Cycle class    - MUIA_Cycle_Active is ex/imported.
  1368.     List class     - MUIA_List_Active is /ex/imported.
  1369.     Text class     - MUIA_Text_Contents is ex/imported.
  1370.     Slider class   - MUIA_Slider_Level is ex/imported.
  1371.     Area class     - MUIA_Selected is ex/imported
  1372.                      (e.g. for Checkmark gadgets)
  1373.    Menuitem class - MUIA_Checked is ex/imported (V9).
  1374.     Group class    - MUIA_Group_ActivePage is ex/imported (V8).
  1375.  
  1376.     INPUTS
  1377.     name - Name of the file you wish to save the settings to.
  1378.            Usually you won't need to think of a real name but
  1379.            instead use one of the magic cookies
  1380.            MUIV_Application_Save_ENV or
  1381.            MUIV_Application_Save_ENVARC.
  1382.            This will save your application's settings somewhere
  1383.            in env:mui/ or envarc:mui/, you needn't worry about
  1384.            it.
  1385.  
  1386.     EXAMPLE
  1387.     see the sample program "Settings.c"
  1388.  
  1389.     SEE ALSO
  1390.     MUIM_Application_Load, Notify.mui/MUIA_ObjectID
  1391. Application.mui/MUIM_Application_SetConfigItem
  1392.  
  1393.     NAME
  1394.     MUIM_Application_SetConfigItem (V11)
  1395.  
  1396.     SYNOPSIS
  1397.     DoMethod(obj,MUIM_Application_SetConfigItem,ULONG item, APTR data);
  1398.  
  1399.     FUNCTION
  1400.     Private method, only for PSI.
  1401. Application.mui/MUIM_Application_SetMenuCheck
  1402.  
  1403.     NAME
  1404.     MUIM_Application_SetMenuCheck (V4 ) (OBSOLETE)
  1405.  
  1406.     SYNOPSIS
  1407.     DoMethod(obj,MUIM_Application_SetMenuCheck,ULONG MenuID, LONG stat);
  1408.  
  1409.     FUNCTION
  1410.     Set or clear the checkmark of a menu item.
  1411.     The application will ask its sub windows for menu items
  1412.     with the given id and set/clear all found
  1413.     entries.
  1414.  
  1415.     INPUTS
  1416.     MenuID - the value you wrote into the
  1417.                  UserData field of struct NewMenu.
  1418.  
  1419.     set    - TRUE to set checkmark, FALSE to clear
  1420.  
  1421.     SEE ALSO
  1422.     MUIM_Application_GetMenuCheck, MUIA_Application_Menu,
  1423. Application.mui/MUIM_Application_SetMenuState
  1424.  
  1425.     NAME
  1426.     MUIM_Application_SetMenuState (V4 ) (OBSOLETE)
  1427.  
  1428.     SYNOPSIS
  1429.     DoMethod(obj,MUIM_Application_SetMenuState,ULONG MenuID, LONG stat);
  1430.  
  1431.     FUNCTION
  1432.     Enable or disable a menu item.
  1433.     The application will ask its sub windows for menu items
  1434.     with the given id and enable/disable all found
  1435.     entries.
  1436.  
  1437.     INPUTS
  1438.     MenuID - the value you wrote into the
  1439.                  UserData field of struct NewMenu.
  1440.  
  1441.     set    - TRUE to enable item, FALSE to disable.
  1442.  
  1443.     SEE ALSO
  1444.     MUIM_Application_GetMenuState, MUIA_Application_Menu,
  1445. Application.mui/MUIM_Application_ShowHelp
  1446.  
  1447.     NAME
  1448.     MUIM_Application_ShowHelp (V4 )
  1449.  
  1450.     SYNOPSIS
  1451.     DoMethod(obj,MUIM_Application_ShowHelp,Object *window, char *name, char *node, LONG line);
  1452.  
  1453.     FUNCTION
  1454.     Show an AmigaGuide help file. The application will be
  1455.     put to sleep until the file is displayed.
  1456.  
  1457.     Usually, you don't need to call this method directly.
  1458.     MUI comes with a sophisticated online help system,
  1459.     you just need to supply your gadgets with help nodes
  1460.     and everything will be handled automatically.
  1461.  
  1462.     INPUTS
  1463.     window - (Object *) - Help will appear on this windows
  1464.                           screen. May be NULL.
  1465.     name   - (char *)   - name of the help file
  1466.     node   - (char *)   - name of a node in this help file
  1467.     line   - (char *)   - line number
  1468.  
  1469.     SEE ALSO
  1470.     MUIA_HelpFile, MUIA_HelpNode, MUIA_HelpLine
  1471.